PR Description

Problem / Motivation

Analysis of the REST Admin API middleware revealed a critical timing side-channel security vulnerability in how Bearer tokens are validated.

In humane_proxy/api/admin.py's _require_admin dependency, the HUMANE_PROXY_ADMIN_KEY extracted from the environment was compared against the incoming request credentials using Python's standard inequality operator (!=).

Because standard string equality compares strings character-by-character and short-circuits upon encountering the first mismatch, it introduces a measurable timing discrepancy based on how many characters of the client's payload match the actual secret. An attacker can leverage this timing side-channel (CWE-208) to brute-force the HUMANE_PROXY_ADMIN_KEY over the network, thereby granting them full access to all /admin endpoints (such as exporting or deleting sensitive escalation records).

Proposed Fix

This PR replaces the short-circuiting inequality operator (!=) with hmac.compare_digest from the Python standard library.

hmac.compare_digest is specifically designed for cryptographic constant-time comparison. It performs a uniform, constant-time comparison of the two string values regardless of whether, or where, the characters mismatch. This entirely closes the timing side-channel vulnerability.

Technical Changes

We imported the hmac module and updated _require_admin in admin.py:

diff --git a/humane_proxy/api/admin.py b/humane_proxy/api/admin.py
index f83dea1..ecd174c 100644
--- a/humane_proxy/api/admin.py
+++ b/humane_proxy/api/admin.py
@@ -19,6 +19,7 @@ Endpoints:
 from __future__ import annotations
 
 import csv
+import hmac
 import io
 import json
 import logging
@@ -60,7 +61,7 @@ def _require_admin(
                 "environment variable to enable it."
             ),
         )
-    if credentials is None or credentials.credentials != admin_key:
+    if credentials is None or not hmac.compare_digest(credentials.credentials, admin_key):
         raise HTTPException(
             status_code=401,
             detail="Invalid or missing Bearer token.",

Verification & Testing

All tests have been run locally to ensure correctness and that no regressions are introduced.

1. Admin Authentication Tests: Verified that valid tokens successfully authenticate, and missing or invalid tokens result in the correct 401 Unauthorized / 403 Forbidden status codes.
2. Whole Test Suite: Ran the entire test suite to ensure the system is completely stable:

   python -m pytest ..\tests

   Result: 214 passed, 13 skipped (0 failures).

Compliance and Checklist

• Fixes CWE-208 timing side-channel vulnerability
• Uses Python standard library (hmac.compare_digest) for constant-time comparison
• All unit and integration tests passed cleanly
• No breaking API changes or configurations introduced